A-用户授权管理 | 文档中心

一、用户授权管理

1、授权信息说明

调用 XLinkUserAuthorizeTask 或 XLinkThirdPartyAuthorizeTask 后，XAPP SDK 内部会维护一个 XLinkUser 对象，里面包含了通讯所需的授权信息：

public class XLinkUser{
    //授权信息
    private String mAccessToken;
    //用于刷新当前授权信息的token
    private String mRefreshToken;
    //CM登录授权信息
    private String mAuthString;
    //用户ID
    private int mUid;
}

此对象可通过如下方法取出：

//通过用户管理对象
XLinkUser user = XLinkUserManager.getInstance().getUser();
//通过SDK直接获取
XLinkUser user = XLinkSDK.getUser();

注意事项：
1.请不要修改 XLinkUser 对象内的授权信，APP 运行时，XAPP SDK 会自动更新 XLinkUser 内部的授权信息。

2.开发者应避免自己缓存 XLinkUser 里的属性（例如把 accessToken 存在一个变量里）,应在每次需要的时候直接调用 XLinkUserManager.getInstance().getUser() 取出授权信息。

用户管理对象中提供了快捷获取相关授权信息的方法

//获取授权信息
XLinkUserManager.getInstance().getAccessToken();
//获取刷新token
XLinkUserManager.getInstance().getRefreshToken();
//获取用户ID
XLinkUserManager.getInstance().getUid();
//获取CM授权信息
XLinkUserManager.getInstance().getAuthString();

2、快捷登录授权

APP 首次打开时（未有用户信息），应跳转至登录页面让用户登陆。登陆动作应包含运行 XLinkUserAuthorizeTask 或 XLinkThirdPartyAuthorizeTask 。

如果要实现用户在下次打开 APP 时跳过登陆动作，那么在首次授权成功时需要保存授权信息，以便下一次快捷登录授权。

2.1、新快捷登录授权（自v6.2版本起）

自v6.2版本起，提供了一种新的快捷登录方式，该方式的目的与原快捷登录功能是一致的，但是解决了原功能可能潜在的问题。原快捷登录方式将用户信息提供给 XAPP SDK 后，XAPP SDK会自动在后台连接到云端服务器，但是存在可能是用户信息是无效或者过期，此时连接肯定失败，XAPP SDK 会通过回调通知用户信息无效。

在实际的应用场景中，可能会造成用户进入主界面后由于用户信息失效导致了需要返回登录界面进行重新登录；针对此情况可使用新的快捷登录授权方式进行处理。新的快捷登录方式将以任务的形式提供，允许设置在超时时间内尝试快捷登录，如果快捷登录失败了则会回调相应的错误信息；

XLinkConfig config = new XLinkConfig.Builder()
        ...
        .build();
XLinkAndroidSDK.init(config);
XLinkSDK.start();
 
//必须启动 SDK 之后才能执行任务
XLinkRefreshTokenTask task = XLinkRefreshTokenTask.newBuilder()
        .setRefreshToken(storgeRefreshToken)
        .setAuthString(storgeAuthString)
        .setUserId(storgeUid)
        .setListener(listener)
        .build();
XLinkSDK.startTask(task);

注意事项：
1.如果刷新凭证无效时，可能会在任务中止时停止 XAPP SDK 的运行，请注意在后续任务执行时需要重新启动 XAPP SDK，XAPP SDK 允许重复启动

2.当使用此新快捷登录方式，请不要在初始化 XAPP SDK 时设置 XLinkUser 信息，一旦在初始化时设置了用户信息，则会以原快捷登录授权方式进行处理，二者可能会造成冲突

3.此任务执行时会自动使用用户信息进行云端登录操作

2.2、原快捷登录授权（不推荐使用）

通过在初始化 XAPP SDK 时提供用户授权信息，XAPP SDK 将自动使用该用户授权信息连接到云端服务器而不需要进行登录。

//新建XLinkUser对象，设置保存了的授权信息
//AccessToken、RefreshToken、Uid、AuthString四个信息缺一不可
XLinkUser lastUser = new XLinkUser();
lastUser.setAccessToken(storgeAccessToken);
lastUser.setRefreshToken(storgeRefreshToken);
lastUser.setUid(storgeUid);
lastUser.setAuthString(storgeAuthString);
 
XLinkConfig config = new XLinkConfig.Builder()
                ...
                // 设置授权信息
                .setXLinkUser(lastUser)
                ...
                .build();

设置好以后，在XLinkSDK.start()的同时，XAPP SDK会自动验证授权信息是否合法，合法则进行后续一系列的云端操作和内部操作。

3、重新授权

一般来说，需要重新授权有如下几个原因：

用户被踢出（单点登录）
token过期（含缺失，格式错误等原因）
用户主动退出

当出现如上情况时，XLinkUserListener 相关方法会回调：

public void onUserLogout(LogoutReason reason) {
    switch (reason) {
        case SINGLE_SIGN_KICK_OFF:
            //用户被踢出
            break;
        case TOKEN_EXPIRED:
            //过期
            break;
        case USER_LOGOUT:
            //用户主动退出
            break;
    }
}

退出登录原因	操作建议
SINGLE_SIGN_KICK_OFF TOKEN_EXPIRED	主动调用`XLinkSDK.logoutAndStop()`停止XAPP SDK并需要重新登录
USER_LOGOUT	勿需特殊操作（因为 USER_LOGOUT 由`XLinkSDK.logoutAndStop()`触发）

注意事项：XLinkSDK.logoutAndStop() 操作会触发USER_LOGOUT事件,处理时请注意避免由于在USER_LOGOUT事件中重复调用该方法引起造成循环逻辑

4、用户凭证维护

在 XAPP SDK 中，默认情况下都会维护授权信息（凭证包含在授权信息中）。登录后获取到的授权信息如下：

{
  //调用凭证
  "access_token": "110ABC119EDF120",
  //刷新凭证
  "refresh_token": "110ABC119EDF120",
  //用户ID
  "user_id": "110120119",
  //有效期（单位：秒）
  "expire_in": "7200",
  //认证码
  "authorize": "110abc119edf120"
}

存在两种不同作用的凭证：调用凭证（简称凭证）与刷新凭证

登录后获取到的用户信息中包括了调用凭证和刷新凭证，其中调用凭证用于所有需要授权信息的接口，但是时效比较短（约2小时）；刷新凭证时间较长(以天为单位，约14天)。所有的请求中需要使用的是有效的调用凭证，刷新凭证不用于授权作用
当调用凭证过期后，在刷新凭证的有效期内可以通过刷新凭证更新并继续使用

在 XAPP SDK 中，当调用凭证无效时，会尝试使用刷新作证去刷新，当无法正常刷新时，才会提示凭证（token）是过期的。所以一般情况下，只要 XAPP SDK 使用是正常的，那么通过以下方式获取到的凭证都是正常可以用的。

XLinkUserManager.getInstance().getAccessToken();

注意事项：强烈建议即取即用，即使是短时间的使用也不要保存起来使用，因为无法确认是否下一秒中调用凭证就可能被刷新掉了。

如果是使用到 restful 接口中一些已有的接口，可以直接通过以下方式调用已有的接口，该请求中是会直接使用 XAPP SDK 中维护的凭证而不需要额外的任何处理。

XLinkRestful.getInstance().getApplicationApi().xxx

注意事项：必须 XAPP SDK 已经初始化过才能正常使用 XLinkRestful

二、更新说明

日期	更新内容
2019-01-16	文本校准，新增用户凭证维护说明

上次更新：2024-05-09